home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 2 / Amiga Tools 2.iso / grafik / bildanzeiger / superview-lib_dev / docs / svobject_ref_eng.doc < prev    next >
Text File  |  1995-03-09  |  19KB  |  843 lines
  1.  
  2.    $VER: SVObject_Ref_ENG.doc V2.3 (16.8.94)
  3.  
  4.    © 1994 by Andreas R. Kleinert. All rights reserved.
  5.  
  6.    - Feel free to translate this Doc-File into other languages. -
  7.  
  8.           Andreas R. Kleinert,
  9.           Grube Hohe Grethe 23,
  10.           D-57074 Siegen,
  11.           Germany.
  12.  
  13.     Phone:  +49-271-331859 (weekdays after 18.00h)
  14.             +49-271-332147 (weekdays after 18.00h)
  15.     EMail:  Fido             Andreas Kleinert 2:2457/345.10
  16.             Usenet/InterNet  Andreas_Kleinert@superview.ftn.sub.org
  17.  
  18.       If nothing else works, try one of these Fido-InterNet gateways:
  19.  
  20.             Andreas_Kleinert@p10.f345.n2457.z2.fido.sub.org (Germany)
  21.             Andreas_Kleinert@p10.f345.n2457.z2.fidonet.org  (US)
  22.  
  23.  
  24.    * DO _NEVER_ ACCESS ANY SVOBJECTS DIRECTLY.
  25.    * DO NEVER BYPASS superview.library !
  26.  
  27.    THE FOLLOWING NOTES ARE ONLY FOR PROGRAMMERS OF SVOBJECTS :
  28.  
  29.    Here is a listing of the function set, which any of the version 1
  30.    and version 2 SVObjects does contain, in an Autodoc-like style of
  31.    description :
  32.  
  33.         SVO_AllocHandle            ; since Version 1
  34.         SVO_FreeHandle
  35.         SVO_Show
  36.         SVO_Write
  37.         SVO_CloseDisplay
  38.         SVO_FreeResources
  39.         SVO_SetAccessMode
  40.         SVL_SetScreenType
  41.         SVO_SetWindowFlags
  42.         SVO_SetWindowIDCMP
  43.         SVO_GetScreenAddress
  44.         SVO_GetWindowAddress
  45.         SVO_SetScreenAddress
  46.         SVO_SetWindowAddress
  47.         SVO_SetWriteName
  48.         SVO_SetReadName
  49.         SVO_FileInfoRequest
  50.         SVO_CheckFileType
  51.         SVO_ReadToGfxBuffer        ; since Version 2
  52.         SVO_GetGfxBuffer
  53.         SVO_SetGfxBuffer
  54.  
  55.  (you will never find any notes belonging to "BUGS", because any SVObject
  56.   may have its own ...)
  57.  
  58. -----------------------------------------------------------------------------
  59.    Functions available since Version 1 :
  60. -----------------------------------------------------------------------------
  61.  
  62.    NAME
  63.         SVO_AllocHandle
  64.  
  65.    SYNOPSIS
  66.  
  67.         APTR SVO_AllocHandle(APTR future)
  68.         D0   -$1e            A1
  69.  
  70.    FUNCTION
  71.  
  72.         Allocates a handle for accessing a Graphic via this SVObject.
  73.  
  74.    INPUT(S)
  75.  
  76.         future - always NULL yet
  77.  
  78.    RESULT
  79.  
  80.         A pointer to a new allocated Handle or NULL, if allocation failed.
  81.  
  82.    WARNING
  83.  
  84.         Test, if the result was NULL, or not !
  85.  
  86.    SINCE
  87.  
  88.         ... Version 1 SVObjects.
  89.  
  90.    SEE ALSO
  91.  
  92.         SVO_FreeResources, SVO_FreeHandle
  93.  
  94. -----------------------------------------------------------------------------
  95.  
  96.    NAME
  97.         SVO_FreeHandle
  98.  
  99.    SYNOPSIS
  100.  
  101.         VOID SVO_FreeHandle(APTR handle)
  102.         D0   -$24           A1
  103.  
  104.    FUNCTION
  105.  
  106.        Aborts showing, frees all Resources and delocates a Handle, which has
  107.        been allocated with SVO_AllocHandle before.
  108.  
  109.  
  110.        For programmers of SVObjects :
  111.  
  112.        Note, that this function should call
  113.  
  114.           SVO_CloseDisplay(SVHandle);
  115.           SVO_FreeResources(SVHandle);
  116.  
  117.        internally always. Otherwise memory might be lost, because
  118.        superview.library might only make a call to SVO_FreeHandle(),
  119.        without closing the display/freeing the resources before.
  120.  
  121.    INPUT(S)
  122.  
  123.         handle - a valid handle
  124.  
  125.    RESULT
  126.  
  127.         -
  128.  
  129.    SINCE
  130.  
  131.         ... Version 1 SVObjects.
  132.  
  133.    SEE ALSO
  134.  
  135.         SVO_AllocHandle, SVO_CloseDisplay, SVO_FreeResources
  136.  
  137. -----------------------------------------------------------------------------
  138.  
  139.    NAME
  140.         SVO_Show
  141.  
  142.    SYNOPSIS
  143.  
  144.         ULONG SVO_Show(APTR handle)
  145.         D0    -$2a     A1
  146.  
  147.    FUNCTION
  148.  
  149.         Loads and shows the Graphic described by a previously set FileName
  150.         or just shows the Graphic, if already been loaded.
  151.  
  152.         Showing can be aborted either via full delocation of the handle
  153.         or via Closing the Display with SVO_CloseDisplay.
  154.  
  155.    INPUT(S)
  156.  
  157.         handle   - a valid handle
  158.  
  159.    RESULT
  160.  
  161.         NULL or an adequate SVERR-Errorcode.
  162.  
  163.    SINCE
  164.  
  165.         ... Version 1 SVObjects.
  166.  
  167.    SEE ALSO
  168.  
  169.         SVO_AllocHandle, SVO_CloseDisplay, SVO_FreeHandle
  170.  
  171. -----------------------------------------------------------------------------
  172.  
  173.    NAME
  174.         SVO_Write
  175.  
  176.    SYNOPSIS
  177.  
  178.         ULONG SVO_Write(APTR handle)
  179.         D0    -$30      A1
  180.  
  181.    FUNCTION
  182.  
  183.         Writes the currently loaded (as GfxBuffer) or displayed (on Screen)
  184.         graphic into a file (or onto any other medium, e.g. ClipBoard),
  185.         which has been specified via the appropriate function calls
  186.         before (SVO_SetAccessMode())
  187.  
  188.    INPUT(S)
  189.  
  190.         handle        - a valid handle
  191.  
  192.    RESULT
  193.  
  194.         NULL or an adequate SVERR-Errorcode.
  195.  
  196.    SINCE
  197.  
  198.         ... Version 1 SVObjects.
  199.  
  200.    SEE ALSO
  201.  
  202.  
  203.         SVO_AllocHandle, SVO_FreeHandle
  204.  
  205. -----------------------------------------------------------------------------
  206.  
  207.    NAME
  208.         SVO_CloseDisplay
  209.  
  210.    SYNOPSIS
  211.  
  212.         VOID SVO_CloseDisplay(APTR handle)
  213.         D0   -$36             A1
  214.  
  215.    FUNCTION
  216.  
  217.         Aborts showing the Graphic, indentified by the handle.
  218.         The Display-Screen is closed, but no other resources are given free.
  219.  
  220.    INPUT(S)
  221.  
  222.         handle - a valid handle
  223.  
  224.    RESULT
  225.  
  226.         -
  227.  
  228.    SINCE
  229.  
  230.         ... Version 1 SVObjects.
  231.  
  232.    SEE ALSO
  233.  
  234.         SVO_FreeResources, SVO_FreeHandle
  235.  
  236. -----------------------------------------------------------------------------
  237.  
  238.    NAME
  239.         SVO_FreeResources
  240.  
  241.    SYNOPSIS
  242.  
  243.         VOID SVO_FreeResources(APTR handle)
  244.         D0   -$3c              A1
  245.  
  246.    FUNCTION
  247.  
  248.         Frees all resources belonging to the specific Graphic,
  249.         indentified by the handle, which are not needed to just show it.
  250.         The display as such will not be closed.
  251.  
  252.         Note, that SVO_FileInfoRequest() will no longer work, then
  253.         ("No file loaded" or similar request appears).
  254.  
  255.    INPUT(S)
  256.  
  257.         handle - a valid handle
  258.  
  259.    RESULT
  260.  
  261.         -
  262.  
  263.    SINCE
  264.  
  265.         ... Version 1 SVObjects.
  266.  
  267.    SEE ALSO
  268.  
  269.         SVO_AllocHandle, SVO_CloseDisplay, SVO_FreeHandle
  270.  
  271. -----------------------------------------------------------------------------
  272.  
  273.    NAME
  274.         SVO_SetAccessMode
  275.  
  276.    SYNOPSIS
  277.  
  278.         ULONG SVO_SetAccessMode(APTR handle, ULONG mode)
  279.         D0    -$42              A1           D1
  280.  
  281.    FUNCTION
  282.  
  283.         Initializes a Handle e.g. for AmigaDOS access, so that the
  284.         separately specified AmigaDOS FileName will be used.
  285.         Another possibility is sometimes to initialize Handles
  286.         for ClipBoard Access (depending on the specific SVObject,
  287.         e.g. IFF-ILBM).
  288.  
  289.    INPUT(S)
  290.  
  291.         handle - a valid handle
  292.         mode   - one of the supported "medium" Flags
  293.  
  294.    RESULT
  295.  
  296.         NULL or an adequate SVERR-Errorcode.
  297.  
  298.    SINCE
  299.  
  300.         ... Version 1 SVObjects.
  301.  
  302.    SEE ALSO
  303.  
  304.         SVO_SetWriteName
  305.  
  306. -----------------------------------------------------------------------------
  307.  
  308.    NAME
  309.         SVL_SetScreenType
  310.  
  311.    SYNOPSIS
  312.  
  313.         ULONG SVL_SetScreenType(APTR handle, ULONG type, APTR future)
  314.         D0    -$48              A1              D1          A2
  315.  
  316.    FUNCTION
  317.  
  318.         Specifies, which ScreenType the Screen should have, on which the
  319.         graphic is to be displayed later.
  320.  
  321.         This statement may have no effect, if the SVObject uses external
  322.         drivers for displaying (e.g. EGS.svdriver will ignore this
  323.         setting more or less).
  324.  
  325.    INPUT(S)
  326.  
  327.         handle - a valid handle
  328.         type   - a ScreenType descriptor, like e.g. CUSTOMSCREEN
  329.         future - always NULL yet
  330.  
  331.    RESULT
  332.  
  333.         NULL or an adequate SVERR-Errorcode.
  334.  
  335.    SINCE
  336.  
  337.         ... Version 1 SVObjects.
  338.  
  339.    SEE ALSO
  340.  
  341.         SVO_GetScreenAddress
  342.  
  343. -----------------------------------------------------------------------------
  344.  
  345.    NAME
  346.         SVO_SetWindowFlags
  347.  
  348.    SYNOPSIS
  349.  
  350.         ULONG SVO_SetWindowFlags(APTR handle, ULONG flags, APTR future)
  351.         D0    -$4e               A1           D1           A2
  352.  
  353.    FUNCTION
  354.  
  355.         Specifies, which Flags the Window should have, on which the
  356.         graphic is to be displayed later.
  357.  
  358.         This statement may have no effect, if the SVObject uses external
  359.         drivers for displaying (e.g. EGS.svdriver will ignore this
  360.         setting more or less).
  361.  
  362.    INPUT(S)
  363.  
  364.         handle     - a valid handle
  365.         flags      - valid WindowFlags, like e.g. WFLG_BACKDROP
  366.         future     - always NULL yet
  367.  
  368.    RESULT
  369.  
  370.         NULL or an adequate SVERR-Errorcode.
  371.  
  372.    SINCE
  373.  
  374.         ... Version 1 SVObjects.
  375.  
  376.    SEE ALSO
  377.  
  378.         SVO_Write
  379.  
  380. -----------------------------------------------------------------------------
  381.  
  382.    NAME
  383.         SVO_SetWindowIDCMP
  384.  
  385.    SYNOPSIS
  386.  
  387.         ULONG SVO_SetWindowIDCMP(APTR handle, ULONG idcmp, APTR future)
  388.         D0    -$54               A1           D1           A2
  389.  
  390.    FUNCTION
  391.  
  392.         Specifies, which IDCMP the Window should have, on which the
  393.         graphic is to be displayed later.
  394.  
  395.         This statement may have no effect, if the SVObject uses external
  396.         drivers for displaying (e.g. EGS.svdriver will ignore this
  397.         setting more or less).
  398.  
  399.    INPUT(S)
  400.  
  401.         handle - a valid handle
  402.         idcmp  - a valid set of IDCMP-Flags
  403.         future - always NULL yet
  404.  
  405.    RESULT
  406.  
  407.         NULL or an adequate SVERR-Errorcode.
  408.  
  409.    SINCE
  410.  
  411.         ... Version 1 SVObjects.
  412.  
  413.    SEE ALSO
  414.  
  415.         SVO_Show
  416.  
  417. -----------------------------------------------------------------------------
  418.  
  419.    NAME
  420.         SVO_GetScreenAddress
  421.  
  422.    SYNOPSIS
  423.  
  424.         struct Screen *SVO_GetScreenAddress(APTR handle, future)
  425.         D0             -$5a                 A1           A2
  426.  
  427.    FUNCTION
  428.  
  429.         While displaying, the address of the DisplayScreen is returned
  430.         by this function.
  431.         See example SourceCodes for more and detailed information.
  432.  
  433.    INPUT(S)
  434.  
  435.         handle - a valid handle
  436.         future - always NULL yet
  437.  
  438.    RESULT
  439.  
  440.         A valid ScreenPointer or NULL.
  441.  
  442.    SINCE
  443.  
  444.         ... Version 1 SVObjects.
  445.  
  446.    SEE ALSO
  447.  
  448.         SVO_GetWindowAddress
  449.  
  450. -----------------------------------------------------------------------------
  451.  
  452.    NAME
  453.         SVO_GetWindowAddress
  454.  
  455.    SYNOPSIS
  456.  
  457.         struct Window *SVO_GetWindowAddress(APTR handle, future)
  458.         D0             -$60                 A1           A2
  459.  
  460.    FUNCTION
  461.  
  462.         While displaying, the address of the DisplayWindows is returned
  463.         by this function.
  464.         See example SourceCodes for more and detailed information.
  465.  
  466.    INPUT(S)
  467.  
  468.         handle - a valid handle
  469.         future - always NULL yet
  470.  
  471.    RESULT
  472.  
  473.         A valid WindowPointer or NULL.
  474.  
  475.    SINCE
  476.  
  477.         ... Version 1 SVObjects.
  478.  
  479.    SEE ALSO
  480.  
  481.         SVO_GetScreenAddress
  482.  
  483. -----------------------------------------------------------------------------
  484.  
  485.    NAME
  486.         SVO_SetScreenAddress
  487.  
  488.    SYNOPSIS
  489.  
  490.         ULONG SVO_SetScreenAddress(APTR handle, struct Screen *sc, APTR future)
  491.         D0    -$66                 A1           A2                 A3
  492.  
  493.    FUNCTION
  494.  
  495.         Sets the address of a Screen, which should be used as the Source
  496.         for the next write action (instead of GfxBuffer).
  497.  
  498.         See description there and example SourceCodes for more and
  499.         detailed information.
  500.  
  501.    INPUT(S)
  502.  
  503.         handle - a valid handle
  504.         sc     - a valid ScreenPointer
  505.         future - always NULL yet
  506.  
  507.    RESULT
  508.  
  509.         NULL or an adequate SVERR-Errorcode.
  510.  
  511.    SINCE
  512.  
  513.         ... Version 1 SVObjects.
  514.  
  515.    SEE ALSO
  516.  
  517.         SVO_SetWindowAddress
  518.  
  519. -----------------------------------------------------------------------------
  520.  
  521.  
  522.    NAME
  523.         SVO_SetWindowAddress
  524.  
  525.    SYNOPSIS
  526.  
  527.         ULONG SVO_SetWindowAddress(APTR handle, struct Window *wi, APTR future)
  528.         D0    -$6c                 A1           A2                 A3
  529.  
  530.    FUNCTION
  531.  
  532.         Sets the address of a Window, which should be used as the Source
  533.         for the next write action (instead of GfxBuffer).
  534.         Also set the corresponding Screen address !
  535.  
  536.         See description there and example SourceCodes for more and
  537.         detailed information.
  538.  
  539.    INPUT(S)
  540.  
  541.         handle - a valid handle
  542.         wi     - a valid WindowPointer
  543.         future - always NULL yet
  544.  
  545.    RESULT
  546.  
  547.         NULL or an adequate SVERR-Errorcode.
  548.  
  549.    SINCE
  550.  
  551.         ... Version 1 SVObjects.
  552.  
  553.    SEE ALSO
  554.  
  555.         SVO_SetScreenAddress
  556.  
  557. -----------------------------------------------------------------------------
  558.  
  559.    NAME
  560.         SVO_SetWriteName
  561.  
  562.    SYNOPSIS
  563.  
  564.         ULONG SVO_SetWriteName(APTR handle, UBYTE *name, APTR future)
  565.         D0    -$72             A1           A2           A3
  566.  
  567.    FUNCTION
  568.  
  569.         Sets a filename for the next write action.
  570.  
  571.    INPUT(S)
  572.  
  573.         handle - a valid handle
  574.         name   - a valid AmigaDOS FileName
  575.         future - always NULL yet
  576.  
  577.    RESULT
  578.  
  579.         NULL or an adequate SVERR-Errorcode.
  580.  
  581.    SINCE
  582.  
  583.         ... Version 1 SVObjects.
  584.  
  585.    SEE ALSO
  586.  
  587.         SVO_SetReadName
  588.  
  589. -----------------------------------------------------------------------------
  590.  
  591.    NAME
  592.         SVO_SetReadName
  593.  
  594.    SYNOPSIS
  595.  
  596.         ULONG SVO_SetReadName(APTR handle, UBYTE *name, APTR future)
  597.         D0    -$78            A1           A2           A3
  598.  
  599.    FUNCTION
  600.  
  601.         Sets a filename for the next read action.
  602.  
  603.    INPUT(S)
  604.  
  605.         handle - a valid handle
  606.         name   - a valid AmigaDOS FileName
  607.         future - always NULL yet
  608.  
  609.    RESULT
  610.  
  611.         NULL or an adequate SVERR-Errorcode.
  612.  
  613.    SINCE
  614.  
  615.         ... Version 1 SVObjects.
  616.  
  617.    SEE ALSO
  618.  
  619.         SVO_SetWriteName
  620.  
  621. -----------------------------------------------------------------------------
  622.  
  623.    NAME
  624.         SVO_FileInfoRequest
  625.  
  626.    SYNOPSIS
  627.  
  628.         ULONG SVO_FileInfoRequest(APTR handle, struct Window *window,
  629.         D0    -$7e                A1           A2
  630.  
  631.                                   APTR future)
  632.                                   A3
  633.  
  634.    FUNCTION
  635.  
  636.         Pops up an Info-Requester with more or less detailed information
  637.         on the currently loaded Graphic.
  638.         A window pointer may be given to select the place to pop it up.
  639.  
  640.         Note, that this function will fail, if you already called
  641.         SVO_FreeResources() (might result in a "No file loaded" message) !
  642.  
  643.    INPUT(S)
  644.  
  645.         handle - a valid handle
  646.         window - a valid Window Pointer or NULL
  647.         future - always NULL yet
  648.  
  649.    RESULT
  650.  
  651.         NULL or an adequate SVERR-Errorcode.
  652.  
  653.    SINCE
  654.  
  655.         ... Version 1 SVObjects.
  656.  
  657.    SEE ALSO
  658.  
  659.         -
  660.  
  661. -----------------------------------------------------------------------------
  662.  
  663.    NAME
  664.         SVO_CheckFileType
  665.  
  666.    SYNOPSIS
  667.  
  668.         ULONG SVO_CheckFileType(BPTR filehandle, UBYTE *filename,
  669.         D0    -$84              A1                 A2
  670.  
  671.                                 struct SVOCheckFile *svo_check)
  672.                                 A3
  673.  
  674.    FUNCTION
  675.  
  676.         Checks, if the given file (or ClipBoard entry, or whatever)
  677.         fits to this SVObject and can be handled therein.
  678.  
  679.         Upto Version 4 of superview.library ClipBoard-Support with
  680.         external SVObjects would not have worked anymore.
  681.  
  682.         Since V4 the specification of external Version 2 SVObjects
  683.         has been modified to allow ClipBoard and other media usage :
  684.         To preserve compatibility, this has been done by using the
  685.         "future" parameter as a pointer to a SVO_CheckFile-structure
  686.         (defined in "include:svobjects/svobjects.h"), which contains
  687.         additional media information (sometimes !).
  688.  
  689.         This pointer may be NULL, so that you have to assume default
  690.         settings, if there's not such a structure.
  691.         For disk-access, this pointer will not be set at all, anyway.
  692.  
  693.         Also be prepared, to handle NULL pointers to filename :
  694.         if ClipBoard usage is forced, there will no filename be needed.
  695.         If you don't support any filename-less medias, just do a silent
  696.         exit.
  697.         Currently - for compatibility reasons - superview.library will
  698.         supply a dummy filename and a dummy file for those SVObjects,
  699.         which may not handle a NULL pointer correctly.
  700.  
  701.         So handle SVOCheckFile structures with a HIGHER priority, because
  702.         currently there's always a dummy-file (mostly empty) available.
  703.  
  704.    INPUT(S)
  705.  
  706.         handle    - a valid handle
  707.         name      - a valid AmigaDOS FileName
  708.         svo_check - a pointer to a SVOCheckFile structure or NULL
  709.                     for disk-access (default)
  710.  
  711.    RESULT
  712.  
  713.         NULL or an adequate SVERR-Errorcode.
  714.  
  715.    SINCE
  716.  
  717.         ... Version 1 SVObjects.
  718.  
  719.    SEE ALSO
  720.  
  721.         -
  722.  
  723. -----------------------------------------------------------------------------
  724.    Functions added with Version 2 :
  725. -----------------------------------------------------------------------------
  726.  
  727.    NAME
  728.         SVO_ReadToGfxBuffer
  729.  
  730.    SYNOPSIS
  731.  
  732.         ULONG SVO_ReadToGfxBuffer(APTR handle)
  733.         D0    -$8a                A1
  734.  
  735.    FUNCTION
  736.  
  737.         Does a read action to a GfxBuffer, using the current settings
  738.         for FileName and medium.
  739.  
  740.         This Buffer may be displayed via SVO_Show and/or exported
  741.         via SVO_GetGfxBuffer.
  742.  
  743.    INPUT(S)
  744.  
  745.         handle    - a valid handle
  746.  
  747.    RESULT
  748.  
  749.         NULL or an adequate SVERR-Errorcode.
  750.  
  751.    SINCE
  752.  
  753.         ... Version 2 SVObjects.
  754.  
  755.    SEE ALSO
  756.  
  757.         SVO_Show, SVO_GetGfxBuffer
  758.  
  759. -----------------------------------------------------------------------------
  760.  
  761.    NAME
  762.         SVO_GetGfxBuffer
  763.  
  764.    SYNOPSIS
  765.  
  766.         ULONG SVO_GetGfxBuffer(APTR handle, struct SV_GfxBuffer **buffer,
  767.         D0    -$90                A1        A2
  768.  
  769.                                ULONG future)
  770.                                A3
  771.  
  772.    FUNCTION
  773.  
  774.         Initializes a given pointer with the address to the GfxBuffer for
  775.         the currently loaded Graphic.
  776.  
  777.         This Buffer MUST NOT be given free by-hand (use SVO_FreeHandle
  778.         or SVO_FreeResources on the main handle) and may still be
  779.         displayed via SVO_Show or saved anywhere else.
  780.  
  781.    INPUT(S)
  782.  
  783.         handle    - a valid handle
  784.         buffer    - a pointer to a SV_GfxBuffer pointer, which should be
  785.                     initialized with a valid pointer
  786.         future    - always NULL yet
  787.  
  788.    RESULT
  789.  
  790.         NULL or an adequate SVERR-Errorcode.
  791.  
  792.    SINCE
  793.  
  794.         ... Version 2 SVObjects.
  795.  
  796.    SEE ALSO
  797.  
  798.         SVO_ReadToGfxBuffer, SVO_Show, SVO_SetGfxBuffer, SVO_Write
  799.  
  800. -----------------------------------------------------------------------------
  801.  
  802.    NAME
  803.         SVO_SetGfxBuffer
  804.  
  805.    SYNOPSIS
  806.  
  807.         ULONG SVO_SetGfxBuffer(APTR handle, struct SV_GfxBuffer *buffer,
  808.         D0    -$90                A1        A2
  809.  
  810.                                ULONG future)
  811.                                A3
  812.  
  813.    FUNCTION
  814.  
  815.         Initializes the given handle with a pointer to a SV_GfxBuffer, which
  816.         should be used for the next write action.
  817.  
  818.         This Buffer STILL HAS TO BE GIVEN FREE the way it has been allocated
  819.         (usually via a SVO_FreeHandle or SVO_FreeResources call with the
  820.         origin handle) and may still be displayed via SVO_Show or saved
  821.         anywhere else.
  822.  
  823.    INPUT(S)
  824.  
  825.         handle    - a valid handle
  826.         buffer    - a pointer to a SV_GfxBuffer pointer, which should be
  827.                     used to initialize the handle for a write action
  828.         future    - always NULL yet
  829.  
  830.    RESULT
  831.  
  832.         NULL or an adequate SVERR-Errorcode.
  833.  
  834.    SINCE
  835.  
  836.         ... Version 2 SVObjects.
  837.  
  838.    SEE ALSO
  839.  
  840.         SVO_ReadToGfxBuffer, SVO_Show, SVO_GetGfxBuffer, SVO_Write
  841.  
  842. -----------------------------------------------------------------------------
  843.